======Template======

=====Template Implementation Notes ======

====Terms:====
  * An individual item in a stored template is called a "template element".
  * The term for "activation" of a template is called "application".
  * That is, one "applies" a template to a running configuration.

====Settings stored in Templates ====
  - Stored templates generally contain a subset of the configuration choices that are available in the global toolbar.
  - Stored templates also contain elements relating to individual canvas display options.
  - Stored templates may optionally contain certain elements that are ignored on application. This is done as a programming convenience.

====Elements Recovered with an Application of a Template====

The following table summarizes the elements which are explicitly recovered when a template is applied to a running configuration. 
A. The following groups of global configuration settings are recovered as template elements.
  - Global toolbar Settings:
     * Display All
     * Charts: All, except 
       * Chart Directory list
       * Plugins currently
     * unimplemented.(e.g ofc, oeSENC, s63)
       * Ships: All, including MMSI properties ("race" template where competitors are listed as "follower")
          * Hakan Comment: We may discuss whether the status of "Warn if CPA is less than..." should be a (global) element or not. So far I think it should. For example I could have one "Within the archipelago" template and one "Outside the...". Here I'd use CPA warnings for the latter only.
       * User Interface: All
       * Plugins All, (n.b. currently unimplemented)
       * Plugin Tools TBD, Plugin implementation dependent.

B. The following individual canvas display options are also recovered as template elements.
  - Navigation Mode (North-up/Course-up)
  - Quilt Mode
  - Show Tides/Currents
  - Show AIS
  - ENC Settings:
       * Show Text
       * Show Soundings
       * Light Descriptions
       * ATON labels
       * Display Category (including "Mariner's Standard")
          * Hakan - Are individual marks saved as elements in a Canvas config/Global config/Not saved?
          * Hakan I saw "ActiveChartGroup=1" is a part of each Canvas config, e.g. a chart group would be changed, if needed, on applying a template? Is that your intention? (Although not yet implemented!?) If so; I agree.
          * Active group list is NOT currently in the template.  Seems a problem if we agree with Hubert that Templates should be system agnostic and portable.  Discuss?
       * Look ahead mode.
     * 
B. The following undocumented or inaccessible global options are storedand recovered as template elements
  * "UIexpert"
  * "DebugGDAL"
  * "DebugNMEA"
  * "DebugOpenGL"
  * "AnchorWatchDefault"
  * "AnchorWatchMax"
  * "GPSDogTimeout"
  * "DebugCM93"
  * "DebugS57"
  * "DebugBSBImg"
  * "DebugGPSD"
  * "GPSIdent"
  * "UseNMEA_GLL"
  * "LegacyInputCOMPortFilterBehaviour"
  * "EnableRotateKeys"
  * "EmailCrashReport"
  * "EnableAISNameCache"
  * "EnableUDPNullHeader"
  * Others, TBD.....

The following table summarizes the elements which are not recovered when a template is "applied" to a running configuration.

A.  The following global items are specifically not recovered  
  - Global toolbar Settings:
     * Connections All
B. The following canvas display options are not recovered.
     * All CanvasOptions items not specifically mentioned in (2)
C. The following objects are not template elements, and are neither stored or recovered.
  - Chart Database.
  - Routes/Waypoints (navobj.xml).
  - Layers, and layer visibility.
  - AIS target MMSI cache.
  - Tides/Currents data files
D.  A running configuration is considered to be equivalent to the last "applied" template only if no items from (1), (2), or (3) above have been changed.

E. Modification are saved to master config file, loaded on next startup. Not automatically saved to last applied template. I will
consider the UI to "save modification to last applied template". This will probably require a user confirmation step, just to be sure the
action is very clear to the user.

==== TABLE: Elements Recovered with an application of a Template ====

^ Global                  ^ Group                ^ Settings ^ Exceptions - Notes             ^
| **Global Configuration settings recovered as template elements**                  ||||
| Global toolbar Settings |                     |          |                                |
|                         | Display             | All      |                                |
|                         | Charts              | All      | Except                         |
|                         |                     |          | Chart Directory List           |  
|                         |                     |          | Plugins currently              |
|                         |Unimplemented        |          | eg ofc, oesenc, s63            |
|                         |Ships                | All      | Except MMSI properties         |
|                         |User Interface       | All      |                                |
|                         |Plugins              | All      | (n.b. currently unimplemented) |     
|                         |Plugin Tools         | TBD      | Plugin Implementation Dependent|
| **Individual canvas display options recovered as template elements**              ||||
|                         | Navigation Mode     | North up, Course up|                 |
|                         | Quilt Mode          |                    |                 |
|                         | Show Tides/Currents |                    |                 |
|                         | Show AIS            |                    |                 |
|                         | ENC Settings:       |                    |                 |
|                         |                     | Show Text          |                 | 
|                         |                     | Show Soundings     |                 |
|                         |                     | Light Descriptions |                 |
|                         |                     | ATON labels        |                 |
|                         |                     | Display Category   |                 |
| **Iinaccessible global options stored and recovered as template elements** ||||
|                         |                     | "UIexpert"         |                 |
|                         |                     | "DebugGDAL"        |                 |
|                         |                     | "DebugNMEA"        |                 |
|                         |                     | "DebugOpenGL"      |                 |
|                         |                     | "AnchorWatchDefault" |                 |
|                         |                     | "AnchorWatchMax"   |                 |
|                         |                     | "GPSDogTimeout"    |                 |
|                         |                     | "DebugCM93"        |                 |
|                         |                     | "DebugS57"         |                 |
|                         |                     | "DebugBSBImg"      |                 |
|                         |                     | "DebugGPSD"        |                 |
|                         |                     | "GPSIdent"         |                 |
|                         |                     | "UseNMEA_GLL"      |                 |
|                         |                     | "LegacyInputCOMPortFilterBehaviour" |                 |
|                         |                     | "EnableRotateKeys"    |                 |
|                         |                     | "EmailCrashReport"    |                 |
|                         |                     | "EnableAISNameCache"  |                 |
|                         |                     | "EnableUDPNullHeader" |                 |
|                         |                     | Others, TBD.....      |                 |


==== TABLE: Elements Not Recovered when a Template is applied to a running configuration ====

^Global  ^Group  ^Settings^Exceptions - Notes  | |
|**Global items specifically not recovered as template elements**   |||| |
|Global toolbar Settings|   |   |   | |
|   |Connections  |All  |   | |
|**Canvas Display options not recovered**   |||| |
|   |Canvas Options  |All not listed above  |||
|**Objects which are not Template Elements, that are neither stored or recovered** |||| |
|   |Chart Database  |   |   | |
|   |Routes Waypoints|navobj.xml|   | |
|   |Layers & Visibl.|   |   | |
|   |AIS target  |MMSI cache|   | |
|   |Tides/Current|Datafiles  |     | |

\\


======Earlier  Notes====
Part of the confusion:
4.99.930 has an error in application templates.  It is applying the
stored chart groups (per-canvas), and also the own-ship location.  This
is not the intent of the design.

Try this:
  - Single canvas, showing a group with KAP charts.
  - Create a template.
  - Switch to a group having ENC's for the same area, or cm93.
  - Apply the template created in 2.  You will be switched to the KAP
group, and the location will shift to the position erroneously recorded
in the template.  This is wrong, according to Hubert's logic, and I
think mine too.

Said another way:
Templates are snapshots of the system configuration recording everything
except:

  - Group selection
  - Ownship Location
  - Chart database contents

In the design, here is a nearly complete subset of of things that are saved:

  - Settings->charts->Vector charts. Everything
  - Settings->Ships. Everything
  - Setting->User Interface. Everything
  - Settings->Plugins. Everything
  - Settings->Connections. Everything
  - Settings->charts->chart groups. Everything
  - Screen canvas config, 1 or two, with split sizes recorded
     * You will see that up to this point, everything saved is "global" in scope.  Nothing to do with specific charts or selected group.
  - Also, a very small subset of items in Canvas Options dialog(s), including maybe:
    * Quilt mode state
    * Show tides/Currents state
    * Chart outlines state
    * Maybe others, opinions solicited.  Undecided on canvas scale/center location.  This could be friendly.

As discovered, A-test shows that we are not quite there in
implementation yet.  Working....

====What Templates are not====

Named templates do not include :
  - Selected chart group.
  - Screen position/scale/rotation.

That is not the purpose of Templates.

Named "goto"s with recorded/restored chart group selections are
something else, entirely.  This will be a separate discussion, deferred
a little bit.  May involve a separate UI method, or may piggyback on
Templates UI.  We shall discuss.

First, let us all understand the concept of named Templates as specified
now.  We should get that right first, and see if we can communicate what
that means to users, sensibly.

Hubert wrote:  In this context the view (gotoview), the actual viewport as result of position and zoom, is part of the *live data* and thus not part of a template.



====About OpenCPN Restart & .ini====

Lets be clear on this point.

O always restarts in the exact same configuration that it exhibited when last shutdown.  It absolutely does not load the last named template which may have been created or loaded in the previous session.

So, at any given point, O may or may not be running a named template exactly.

If a user wants to run strictly a named template, then she must "Apply" that template and make no other global config changes.

Seen in this way, templates are convenient "macro shortcuts" to specific global configurations.

===We have a technical problem here:===

We can certainly record and keep track of the last template applied, and indicate it somehow.  No problem.

And we can also compare the presently running config with all saved templates, and detect which, if any, saved template is active.

However, with an arbitrary config loaded from O startup, it may not match exactly any stored template.  Often won't.  For example, from
initial installation:
  - Template running is, by definition, the "panic" template.
  - Add GPS connection.  Now, the initial template is NOT running.  This is a derivative of the initial template.  There is no saved template that matches.

Not to be argumentative, but what might the user expect to see then?

====More About Restart, Templates & ini====
One more (open) point:

at re-start with a tainted template, what would it show?
Following our philosophy, the latest setting, so the tainted template.

Hubert On 4/10/18 16:05, info-o-charts wrote:
> Now, the spoiled template: sure, when a user modifies the setting brought up by a template, it will not be the identical anymore. It will be tainted.
> In many application a tainted content will be marked by an "*".
> If one sees [* /my favorite template/] instead of [my favorite template] one will know, that something has been modified.
> Does this make sense to you? 

====About Saving Comms ====
This is a new idea to me.
Comms are one of the biggest user problems.  I imagine that when a configuration is (finally) working, a user could create her own "Reset"
template, available anytime.  Such a "user reset" template could be more useful than a generic "panic button", though we would have panic button always. Just my thoughts, not fixed.
Dave

On 10/04/2018 10:05 AM, info-o-charts wrote:
> from my point of view GPS or COMs in general not would be a part of a
> template. Installation dependent.

====About Template & Canvas Menus - Clarity====

Perhaps we should have a new and separate "Settings->Configuration" tab.
 And leave the screen split sub-page as part of "Display".

Will this help lead the newer user to the right intuition?
Opinions?

> Tabs: Maybe not a new Settings tab but;
> - Move "Canvas layout" to Display->General. (Now close to empty.)
> - Keep templates handling in Display->Config. Rename the tab to "Saved
> Templates" or...? (Configurations are not set here!)

I like this.  I will experiment with the Display->General tab layout,
and move the screen canvas selection there.

For the name of the "configs" tab:  "Configs" is ambiguous, and a simple
word I chose to get started. I am not sure of the best universal name,
and how this reasonably translates.  "Saved Templates" works OK in
English, if we use that term consistently in the docs.
How will this be for other languages?

  - Template  https://www.thesaurus.com/browse/template?s=t "as in pattern", mold, stencil, impression
  - Template in Swedish is a mold, something created by anyone else to use as a base for some work. E.g. us a template for a slide show or a drawing. For us it may be the basic settings. A more precise description would be "Saved user configurations". But I can't find a nice single word for that, On the other hand.... since a saved user configuration can be loaded and afterwords the user can change some settings without updating the saved config //and the changes will though be there after O restart// (?). So in that case we've used it as a template. 
  - German "Vorlage" or as "Schablone", where the first refers to a document - what is our case - and the second one to a material piece to be copied or multiplied. That goes into the direction of Hakan's "mold".
  - France "Templates" can be translate by "Modèles" in french.


[[https://opencpn.org/wiki/dokuwiki/doku.php?id=playground:template:discussion|Discussion  What are Templates?]]